<html>
  <head>
    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <title>MARY HTTP Interface: Documentation by example</title>
  </head>

<body onload="initForm();">
<font STYLE="font-family: Verdana">

<img src="favicon.ico" />
<h1 style="display: inline;"><font STYLE="color:#587D9D">MARY HTTP Interface: Documentation by example</font></h1>

<p> This is a simple plain-HTML page showing the various queries that the MARY HTTP server supports.
This is intended as a live documentation for developers who want to use the HTTP interface
to build MARY clients.</p>

<p>All examples below use relative URLs. That is, if this page is shown as
 <code>http://localhost:59125/</code>, you can refer to the relative URL
 <code>version</code> as the absolute URL <code>http://localhost:59125/version</code> etc.</p>

<h2 id="info">Information requests</h2>

<h3 id="version">Server version</h3>
<p>
<code>version</code> requests the version of the MARY server:
</p>
<p><code><a href="version">version</a></code></p>


<h3 id="datatypes">Available data types</h3>
<p>
<code>datatypes</code> requests the list of available data types:
</p>

<p><code><a href="datatypes">datatypes</a></code></p>


<h3 id="locales">Available locales / language components</h3>
<p>
<code>locales</code> requests the list of available locales
</p>

<p><code><a href="locales">locales</a></code></p>


<h3 id="voices">Available voices</h3>
<p>
<code>voices</code> requests the list of available voices
</p>

<p><code><a href="voices">voices</a></code></p>



<h3 id="exampletext">Example texts</h3>
<p>
<code>exampletext?datatype=(datatype)&locale=(locale)</code>
requests the example text for the given datatype and locale, e.g.:
</p>

<p><code><a href="exampletext?datatype=RAWMARYXML&locale=en_US">exampletext?datatype=RAWMARYXML&locale=en_US</a></code></p>

<p>
<code>exampletext?voice=(voicename)</code> requests the example text for the given voice.
This makes sense in case of limited domain voices, e.g.:
</p>

<p><code><a href="exampletext?voice=dfki-bundesliga">exampletext?voice=dfki-bundesliga</a></code></p>


<h3 id="features">Available target features</h3>

<p>Much processing in MARY uses the concept of a feature vector, abstracting a broad range
of linguistic and acoustic analyses into byte-valued, short-valued and continuous features
which can be computed for every phone or every halfphone in an input sentence.</p>

<p><code>features?locale=(locale)</code> requests the list of available features that can be computed for the given locale, e.g.:</p>

<p><code><a href="features?locale=en">features?locale=en</a></code></p>

<p><code>features?voice=(voicename)</code> requests the list of available features that can be computed for the given voice,
which may or may not be the same as for the voice's locale, e.g.:</p>

<p><code><a href="features?voice=slt-arctic">features?voice=slt-arctic</a></code></p>


<h3 id="audioformats">Audio formats</h3>

<p><code>audioformats</code> requests the list of supported audio file format types.</p>

<p><code><a href="audioformats">audioformats</a></code></p>


<h3 id="audioeffects">Audio effects</h3>

<p>MARY TTS can use audio effects to modify the synthesis output.</p>

<p><code>audioeffects</code> requests the list of available audio effects:</p>

<p><code><a href="audioeffects">audioeffects</a></code></p>

<p><code>audioeffect-default-param?effect=(effectname)</code> requests the default parameters of the given audio effect, e.g.:</p>

<p><code><a href="audioeffect-default-param?effect=Robot">audioeffect-default-param?effect=Robot</a></code></p>

<p><code>audioeffect-full?effect=(effectname)&params=(parameter-settings)</code> requests a full description of the given audio effect, including effect name, parameters and help text, e.g.:</p>

<p><code><a href="audioeffect-full?effect=Robot&params=amount:100.0">audioeffect-full?effect=Robot&params=amount:100.0</a></code></p>

<p><code>audioeffect-help?effect=(effectname)</code> requests a help text describing the given audio effect, e.g.:</p>

<p><code><a href="audioeffect-help?effect=Robot">audioeffect-help?effect=Robot</a></code></p>

<p><code>audioeffect-is-hmm-effect?effect=(effectname)</code> requests a boolean value (plain text "yes" or "no") indicating whether or not the given effect is an effect that operates on HMM-based voices only, e.g.:</p>

<p><code><a href="audioeffect-is-hmm-effect?effect=Robot">audioeffect-is-hmm-effect?effect=Robot</a></code></p>


<h3 id="vocalizations">Vocalizations</h3>

<p>Some voices can generate non-verbal or listener vocalizations such as "(laughter)", "yeah", "hmm" etc. The list of vocalizations that can be generated depends on the voice.
An empty list indicates that the voice does not support vocalizations.</p>

<p><code>vocalizations?voice=(voicename)</code> requests the list of vocalizations available for a given voice.</p>

<p>For example:</p>

<p><code><a href="vocalizations?voice=dfki-poppy">vocalizations?voice=dfki-poppy</a></code></p>
<p><code><a href="vocalizations?voice=dfki-prudence">vocalizations?voice=dfki-prudence</a></code></p>
<p><code><a href="vocalizations?voice=dfki-spike">vocalizations?voice=dfki-spike</a></code></p>
<p><code><a href="vocalizations?voice=dfki-obadiah">vocalizations?voice=dfki-obadiah</a></code></p>

<p>The following is an example document in WORDS format that requests a vocalization:</p>

<pre>
&lt;maryxml version="0.5" xmlns="http://mary.dfki.de/2002/MaryXML" xml:lang="en-GB"&gt;
&lt;voice name="dfki-poppy"&gt;
&lt;p&gt;
&lt;vocalization name="yeah" meaning="uncertain" intonation="falling" voicequality="modal"/&gt;
&lt;/p&gt;
&lt;/voice&gt;
&lt;/maryxml&gt;
</pre>

<h3 id="styles">Speaking styles</h3>

<p>Some voices can produce speech with different speaking styles. The list of styles that can be generated depends on the voice.
An empty list indicates that the voice does not support styles.</p>

<p><code>styles?voice=(voicename)</code> requests the list of styles available for a given voice.</p>

<p>For example:</p>

<p><code><a href="styles?voice=dfki-pavoque-styles">styles?voice=dfki-pavoque-styles</a></code></p>

<p>The following is an example document in RAWMARYXML format that requests a happy speaking style:</p>

<pre>
&lt;maryxml version="0.5" xmlns="http://mary.dfki.de/2002/MaryXML" xml:lang="de"&gt;
&lt;voice name="dfki-pavoque-styles"&gt;
&lt;prosody style="happy"&gt;
Ist das nicht eine schöne Blume!
&lt;/prosody&gt;
&lt;/voice&gt;
&lt;/maryxml&gt;
</pre>


<h2 id="synthesis">Synthesis requests</h2>

<p><code>process</code> requests the synthesis of some text.</p>

<p>It can be called as a GET or a POST request, using the following parameters:

<ul>
  <li><code>INPUT_TEXT</code> (required) is the text to be processed.</li>
  <li><code>INPUT_TYPE</code> (required) is the data type of the input text. It must be one of the input <a href="#datatypes">data types</a>.</li>
  <li><code>OUTPUT_TYPE</code> (required) is the data type to be generated as output. It must be one of the output <a href="#datatypes">data types</a>.</li>
  <li><code>LOCALE</code> (required) is the locale of the input text -- either a language (e.g., <code>en</code>) or a language and country (e.g., <code>en_US</code>).</li>
  <li><code>AUDIO</code> (required only if OUTPUT_TYPE=AUDIO) is the format in which to send the synthesized audio. It must be one of the available <a href="#audioformats">audio formats</a>.</li>
  <li><code>OUTPUT_TYPE_PARAMS</code> (optional) can be used to provide additional information regarding the requested output format. The only use at the moment is in connection with the output types <code>TARGETFEATURES</code> and <code>HALFPHONE_TARGETFEATURES</code>, where it can list the selection of <a href="#features">features</a> to compute.</li>
  <li><code>VOICE</code> (optional) is the default voice to use for generating output. If absent, the locale's default voice will be used for producing audio.</li>
  <li><code>STYLE</code> (optional) can be used for requesting a given speaking style for voices supporting this feature (none yet).</li>
  <li><code>LOG</code> (optional) can be used for logging some information in the server's log file.</li>
  <li><code>effect_(effectname)_selected</code> (optional) can be used to indicate whether the named effect should be applied (value is <code>on</code>) or not (value is <code>off</code>).</li>
  <li><code>effect_(effectname)_parameters</code> (optional) can be used to transport the parameters to use for the named effect.</li>
</ul>

<h3>GET examples</h3>

<p>Simple text to speech for the text <code>Hello world</code> using the default US english voice to produce WAVE output data:</p>
<p><code><a href="process?INPUT_TEXT=Hello+world&INPUT_TYPE=TEXT&OUTPUT_TYPE=AUDIO&AUDIO=WAVE_FILE&LOCALE=en_US">process?INPUT_TEXT=Hello+world&amp;INPUT_TYPE=TEXT&amp;OUTPUT_TYPE=AUDIO&amp;AUDIO=WAVE_FILE&amp;LOCALE=en_US</a></code></p>


<p>Partial processing of data: convert <code>Hello world</code> into ACOUSTPARAMS format, the full XML format used inside MARY TTS:</p>
<p><code><a href="process?INPUT_TEXT=Hello+world&INPUT_TYPE=TEXT&OUTPUT_TYPE=ACOUSTPARAMS&LOCALE=en_US">process?INPUT_TEXT=Hello+world&amp;INPUT_TYPE=TEXT&amp;OUTPUT_TYPE=ACOUSTPARAMS&amp;LOCALE=en_US</a></code></p>

<p>Computation of feature vectors for <code>Hello world</code> for the features <code>phone stressed accented</code> for every phone:</p>
<p><code><a href="process?INPUT_TEXT=Hello+world&INPUT_TYPE=TEXT&OUTPUT_TYPE=TARGETFEATURES&LOCALE=en_US&OUTPUT_TYPE_PARAMS=phone+stressed+accented">process?INPUT_TEXT=Hello+world&amp;INPUT_TYPE=TEXT&amp;OUTPUT_TYPE=TARGETFEATURES&amp;LOCALE=en_US&amp;OUTPUT_TYPE_PARAMS=phone+stressed+accented</a></code></p>

<p>Simple form containing only the required fields, as a GET request:</p>

<form action="process" method="GET">
  INPUT_TEXT: <input type="text" name="INPUT_TEXT" value="Hello world" /><br />
  INPUT_TYPE: <input type="text" name="INPUT_TYPE" value="TEXT" /><br />
  OUTPUT_TYPE: <input type="text" name="OUTPUT_TYPE" value="AUDIO" /><br />
  LOCALE: <input type="text" name="LOCALE" value="en_US" /><br />
  AUDIO: <input type="text" name="AUDIO" value="WAVE_FILE" /> <br />
  <input type="submit" />
</form>


<h3>POST example</h3>


<p>Simple form containing only the required fields, as a POST request:</p>

<form action="process" method="POST">
  INPUT_TEXT: <input type="text" name="INPUT_TEXT" value="Hello world" /><br />
  INPUT_TYPE: <input type="text" name="INPUT_TYPE" value="TEXT" /><br />
  OUTPUT_TYPE: <input type="text" name="OUTPUT_TYPE" value="AUDIO" /><br />
  LOCALE: <input type="text" name="LOCALE" value="en_US" /><br />
  AUDIO: <input type="text" name="AUDIO" value="WAVE_FILE" /> <br />
  <input type="submit" />
</form>



</font>
</body>
</html>
